1. Introduction
This section is non-normative.
Over the last decade, identity federation has unquestionably played a central role in raising the bar for authentication on the web, in terms of ease-of-use (e.g. passwordless single sign-on), security (e.g. improved resistance to phishing and credential stuffing attacks) and trustworthiness compared to its preceding pattern: per-site usernames and passwords.
The standards that define how identity federation works today on the Web were built independently of the Web Platform (namely, SAML, OpenID and OAuth), and their designers had to (rightfully so) work around its limitations rather than extend them.
Because of that, existing user authentication flows were designed on top of general-purpose web platform capabilities such as top-level navigations/redirects with parameters, window popups, iframes and cookies.
However, because these general purpose primitives can be used for an open ended number of use cases (again, notably, by design), browsers have to apply policies that capture the lowest common denominator of abuse, at best applying cumbersome permissions (e.g. popup blockers) and at worst entirely blocking them (e.g. blocking third party cookies).
Over the years, as these low-level APIs get abused, browsers intervene and federation adjusts itself. For example, popup blockers became common and federation had to adjust itself to work in a world where popups blockers were widely deployed.
The challenge is that some of these low level primitives are getting increasingly abused to allow users on the web to be tracked. So, as a result, browsers are applying stricter and stricter policies around them.
This specification defines a set of high-level APIs that serve as a foundation where identity federation on Web can thrive without incurring into Unsanctioned Web Tracking.
2. Use Cases
The below use case scenarios illustrate some basic supported flows. Additional scenarios, including sample code, are given later in the Identity Use Cases in Browser Catalog.
2.1. Sign-up
A Sign-up occurs when the user is registering a new account at the Relying Party using their Identity Provider.
-
A user navigates to a Relying Party in a browser and decides to create an account.
-
The Relying Party supports multiple Identity Provider as an authentication mechanism.
-
A user selects their favorite Identity Provider to sign-up with.
-
The Identity Provider prompts, "Do you want to create an account with the Relying Party?"
-
The user agrees.
-
The Relying Party shows the message "Registration complete."
-
An account in created in the Relying Party and a session initialized.
2.2. Sign-in
After a user navigates to a Relying Party in a browser and decides to create an account by going through their § 2.1 Sign-up flow, there are two ways a user logs into their account once their session expires:
2.2.1. Auto Sign-in
Auto Sign-in occurs when the Identity Provider has already gathered enough permission from the user to share their identity that it doesn’t block on gathering further permission and automatically signs the user in.
-
Using another device (e.g. their laptop):
-
The user goes to the Relying Party.
-
The user selects their favorite Identity Provider to sign-in.
-
The Identity Provider remembers and proves that the user already has an account with the Relying Party.
-
The Relying Party creates a new session for the user’s existing account.
-
2.2.2. Explicit Sign-in
An explicit sign-in occurs when the Identity Provider believes it is necessary to gather an explicit permission from the user to sign into a Relying Party, typically after the user goes through a § 2.3 Sign-out flow.
-
The user decides to § 2.3 Sign-out of the Relying Party
A few months later:
-
The user navigates to the Relying Party
-
The user selects their favorite Identity Provider to sign-in again.
-
The Identity Provider knows that:
-
the user already has an account with the Relying Party.
-
the user has logged out of the Relying Party.
-
-
The Identity Provider prompts, "Do you want to sign-in with the Relying Party?"
-
The user agrees.
-
The Relying Party creates a new session for the user’s existing account.
2.3. Sign-out
After a user navigates to a Relying Party in a browser and decides to create an account by going through their § 2.1 Sign-up flow, there are two ways a user can clear their sessions:
2.3.1. RP Sign-out
-
On a shared computer:
-
The user decides to close their session and logs out of the Relying Party.
-
The user is now logged out of the Relying Party.
-
Upon return to the Relying Party, the user expects to go through an § 2.2.2 Explicit Sign-in.
-
2.3.2. IDP Sign-out
-
On a shared computer:
-
The user decides to close their session and logs out of the Relying Party.
-
The Relying Party lets the Identity Provider know that the user wants to logout.
-
The Identity Provider logs the user out of all of the Relying Partys and itself.
-
Upon return to the Relying Party, the goes through an § 2.2.2 Explicit Sign-in.
-
2.4. Revocation
After a user navigates to a Relying Party in a browser and decides to create an account by going through their § 2.1 Sign-up flow, there are two ways a user can cancel their account:
2.4.1. IDP Revocation
-
On the Identity Provider:
-
The user decides to cancel their account.
-
The user goes to their Identity Provider and revokes access to the Relying Party.
-
Upon return to the Relying Party, the user expects to go through a § 2.1 Sign-up.
-
2.4.2. RP Revocation
-
On the Relying Party:
-
The user decides to cancel their account.
-
The user navigates to the Relying Party and cancels their account, also letting the Identity Provider know.
-
Upon return to the Relying Party, the user expects to go through a § 2.1 Sign-up.
-
2.5. Access
-
A user navigates to a Relying Party in a browser and decides to create an account.
-
The Relying Party supports multiple Identity Provider which provide access to the user’s Calendar.
-
A user selects their favorite Identity Provider to sign-up with.
-
The Identity Provider prompts, "Do you want to give access to your Calendar to the Relying Party?"
-
The user agrees.
-
The Relying Party shows message, "Registration complete.", creates a session for the user and
-
Shows the user their calendar entries provided by the Identity Provider.
3. Examples
This specification extends the FederatedCredential type and internal algorithms to allow the exchange
of identity between IDPs and RPs. When it succeeds, it returns to the RP a signed id token which the RP can use to authenticate the user.
< html > < head > < title > Welcome to my WebSite!</ title > </ head > < body > < button onclick = "login('https://foo.example', '123')" > Sign-in with Foo</ button > < button onclick = "logout()" > logout</ button > Welcome< span id = "name" ></ span > !!< button onclick = "revoke" > delete account</ button > < script > var user; async function login( provider, clientId) { const { idToken} = await navigator. credentials. get({ // controls whether auto sign-in is enabled or not mediation: "optional" , // controls abortions of the account chooser signal: signal// controls which identity providers to use federated: { // controls whether the account chooser is modal or not providers: [{ url: provider, // the pre-registered client id clientId: clientId, nonce: "456" }], } }); // ... do stuff ... // ... send to server ... // ... validate ... // ... update local storage ... user= parse( idToken); document. getElementById( "name" ). innerText= user. name; } async function logout() { await navigator. credentials. preventSilentAccess(); } async function revoke() { await FederatedCredential. revoke( user. id); } </ script > </ body > </ html >
4. Terminology
HTML Standard defines an origin as the tuple of a scheme, hostname, and port that provides the main security boundary on the web.
A site is a set of origins that are all same site with each other. Note that there are problems (Public Suffix List Problems) with using registrable domains as a logical boundary.
A party is defined by Tracking Preference Expression (DNT) as "a natural person, a legal entity, or a set of legal entities that share common owner(s), common controller(s), and a group identity that is easily discoverable by a user."
The first party for a user action is the party that controls the origin of the top-level browsing context under which the action happened. Intuitively, this is the owner of the domain in the browser’s URL bar. This differs from Mozilla’s definition in that Mozilla defines other parties as first parties if the user can easily discover which party it is and intends to interact with that party, for example to allow sign-in widgets to be first-party.
A third party for a user action is any party that isn’t the first party or the user (the second party).
A user is a human or program that controls a user agent.
A user identifier is a pair of a site and a (potentially-large) integer allocated by that site that is used to identify a user on that site. A single user will generally have many user IDs that refer to them, and a single site may or may not know that multiple user identifiers refer to the same user.
A global identifier is a string that identifies a particular user independent of which site they’re visiting (e.g. email addresses and phone numbers). Users generally have relatively few global identifiers and can usually list and recognize them. A goal of anti-tracking policy is to prevent user identifiers from becoming global identifiers.
A directed identifier is a user identifier that that is unique for each site they’re visiting. A goal of anti-tracking policy is to promote user identifiers to become directed identifiers.
- Relying Party
- RP
- Website
- RP
-
TODO(goto): find existing definitions.
- Identity Provider
- IDP
-
TODO(goto): find existing definition.
- session
-
TODO(goto): find existing definition.
- account
-
TODO(goto): find existing definition.
- id token
-
TODO(goto): find existing definition.
-
unsactioned tracking - high-level API
-
A use case specific API, as opposed to a low-level API. See also high level vs low level.
- low-level API
-
A general purpose API, as opposed to a high-level API. See also high level vs low level
- registered
-
TODO(goto): find existing definition.
- unregistered
-
TODO(goto): find existing definition.
- logged in
-
TODO(goto): find existing definition.
- logged out
-
TODO(goto): find existing definition.
- out-of-band
-
Outside of the user agent’s context.
- joining
5. High Level Design
At a high level, the Identity Federation Management API works by the intermediation of cooperating IDPs and RPs.
The § 6 The Identity Provider API and the § 7 The Relying Party API defines a set of HTTP APIs that cooperating IDPs and IDPs exposes as well as the entry points in the § 8 The Browser API that they can use.
The user agent intermediates in such a matter that makes it impractical for the API to be used for tracking purposes, while preserving the functionality of identity federation.
This document defines the APIs in the following order:
6. The Identity Provider API
The IDP proactively and cooperatively exposes itself as a comformant agent by exposing a series of HTTP endpoints:
-
A § 6.1 Manifest endpoint in a well-known location that points to
-
An § 6.2 Accounts List endpoint
-
A § 6.3 Client Metadata endpoint
-
An § 6.4 ID Token endpoint
-
A § 6.5 Revocation endpoint
6.1. Manifest
The well-known discovery endpoint is an endpoint located at the IDP's .well-known/federated-credentials and serves as a discovery device to other endpoints provided by the IDP.
The well-known discovery endpoint is fetched (a) without cookies and (b) with a special § 6.6 Sec-FedCM-CSRF header.
For example:
GET /.well-known/federated-credentials HTTP / 1.1 Host : idp.example Accept : application/json Sec-FedCM-CSRF : random_value
The file is parsed expecting the following properties:
accounts_endpoint-
A URL that points to an HTTP API that complies with the § 6.2 Accounts List API.
client_id_metadata_endpoint-
A URL that points to an HTTP API that complies with the § 6.3 Client Metadata API.
idtoken_endpoint-
A URL that points to an HTTP API that complies with the § 6.4 ID Token API.
revocation_endpoint-
A URL that points to an HTTP API that complies with the § 6.5 Revocation API.
For example:
{ "accounts_endpoint" : "/accounts.php" , "client_id_metadata_endpoint" : "/metadata.php" , "idtoken_endpoint" : "/idtokens.php" , "revocation_endpoint" : "/revocation.php" }
6.2. Accounts List
The accounts list endpoint provides the list of accounts the user has at the IDP.
The accounts list endpoint is fetched (a) with any cookies and (b) with a special § 6.6 Sec-FedCM-CSRF header.
For example:
GET /accounts_list.php HTTP / 1.1 Host : idp.example Accept : application/json Cookie : 0x23223 Sec-FedCM-CSRF : random_value
The response is expected to have the following properties:
accounts(required)-
A list of Account JSON.
Every Account JSON is expected to have the following properties:
account_id(required)-
An account identifier.
name(required)-
The user’s full name.
given_name(required)-
The user’s given name.
email(optional)-
The user’s email address.
picture(optional)-
The user’s profile picture.
For example:
{ "accounts" : [{ "account_id" : "1234" , "given_name" : "John" , "name" : "John Doe" , "email" : "john_doe@idp.example" , "picture" : "https://idp.example/profile/123" , }, { "account_id" : "5678" , "given_name" : "Johnny" , "name" : "Johnny" , "email" : "johnny@idp.example" , "picture" : "https://idp.example/profile/456" }] }
6.3. Client Metadata
The client metadata endpoint provides metadata about RPs.
The client medata endpoint is fetched (a) without cookies and (b) with a special § 6.6 Sec-FedCM-CSRF header.
The user agent also passes the client_id.
For example:
GET /client_medata.php?client_id=1234 HTTP / 1.1 Host : idp.example Accept : application/json Sec-FedCM-CSRF : random_value
The file is parsed expecting the following properties:
privacy_policy_url-
A link to the RP's privacy policy.
terms_of_service_url-
A link to the RP's terms of service.
For example:
6.4. ID Token
The ID Token endpoint is responsible for minting a new id token for the user.
The ID Token endpoint is fetched (a) as a POST request, (b) with cookies and (c) with a special § 6.6 Sec-FedCM-CSRF header.
It will also contain the following parameters passed as a JSON object:
account_id-
The account identifier that was selected.
request-
The RP request
The RP request has the following properties:
For example:
POST /fedcm_token_endpoint HTTP / 1.1 Host : idp.example Referer : rp.example Content-Type : application/json Cookie : 0x23223 Sec-FedCM-CSRF : random_value {"account_id" : "123" , "request" : { "client_id" : "client1234" , "nonce" : "Ct60bD" } }
The response is parsed as a JSON file expecting the following properties:
id_token-
The resulting id token.
For example:
6.5. Revocation
The revocation endpoint is responsible for revoking all id tokens for the specified client ID for the user.
The revocation endpoint is fetched (a) as a POST request, (b) with cookies, (c) with a special § 6.6 Sec-FedCM-CSRF header, and (d) with a Referer header indicating the RP URL.
It will also contain the following parameters passed as a JSON object:
account_id-
The account identifier for the user (e.g. email).
request
The revocation request has the following properties:
client_id-
The RP's client id
For example:
POST /fedcm_revocation_endpoint HTTP / 1.1 Host : idp.example Referer : rp.example Content-Type : application/json Cookie : 0x23223 Sec-FedCM-CSRF : random_value {"account_id" : "123" , "request" : { "client_id" : "client1234" } }
If successful, the response is an empty response with an HTTP 204 code, otherwise an HTTP error code.
6.6. Sec-FedCM-CSRF
Sec-FedCM-CSRF7. The Relying Party API
RP's expose a § 7.1 Logout to facilitate with § 2.3.2 IDP Sign-out.
7.1. Logout
When IDPs call the § 8.4.2 IDP Sign-out API, every RP gets a chance to log the user out (e.g. clear cookies, clear local storage) via the logout endpoint.
The logout endpoint is an endpoint that is registered with the IDP out-of-band.
The logout endpoint is called (a) with a GET and (b) with the RP's cookies.
Note: the logout API introduces a credentialed request from the IDP to the RPs, so it exposes a potential tracking surface area. It is a fairly limited and controlled tracking area because the logout API is only available when accounts and sessions are already established between the IDP and the RP.
8. The Browser API
The Browser API exposes APIs to RPs and IDPs to call and intermediates the exchange of the user’s identity.
For RPs, it allows them to:
-
The § 8.2 The Sign-in API allows RP's users to § 2.1 Sign-up and § 2.1 Sign-up
-
The § 8.3 The Revocation API allows RP's users to go through § 2.4.2 RP Revocation of their accounts
-
The § 8.4.1 RP Sign-out API allows RPs to § 2.3.1 RP Sign-out of their accounts.
For IDPs, it allows them to:
-
The § 8.4.2 IDP Sign-out API allows IDPs to § 2.3.2 IDP Sign-out of their accounts.
The Browser API manages the lifecycle of the user’s accounts and sessions with an internal § 8.1 The State Machine.
8.1. The State Machine
Internally, the account management and session management APIs allows the user to explicitly move through the different stages of their accounts. At each stage, the state machine manages the RP's and the IDP's access to the appropriate browser capabilities.
Account State-
Keeps track of whether the user has an account or not. Can be registered or (by default) unregistered.
Session State-
Keeps track of whether the user has an open or closed session. Can be logged in or (by default) logged out.
8.2. The Sign-in API
8.2.1. RP Sign-in API
The Sign-up and Sign-in APIs are APIs used by the Relying Partys to ask the browser to intermediate the relationship with the Identity Provider and the provisioning of an id token.
The Relying Party makes no delineation between Sign-up and Sign-in, but rather call the same API indistinguishably. The most important parameter to the API call is the set of Identity Providers that the Relying Party supports and has pre-registered with (i.e. it has a clientId).
Additionally, the Relying Party can control a variety of UX knobs. For example, whether to allow an § 2.2.1 Auto Sign-in flow and an AbortSignal in case it needs to abort the flow.
If all goes well, the Relying Party receives back an id token in the form of a signed JWT which it can use to authenticate the user.
async function login( signal) { const { idToken} = await navigator. credentials. get({ // controls whether auto sign-in is enabled or not mediation: "optional" , // controls abortions of the account chooser signal: signal// controls which identity providers to use federated: { // controls whether the account chooser is modal or not providers: [{ url: "https://idp.example" , // the pre-registered client id clientId: "123" , nonce: "456" }], } }); return idToken; }
To accomplish that, this specification does three things:
-
It extends
FederatedCredentialwith more fields. -
It redefines
FederatedCredential's.[[DiscoverFromExternalSource]]() -
It extends
FederatedCredentialRequestOptionswith more options.
First, this specification extends the FederatedCredential type adding two more fields:
enum {FederatedCredentialApprovedBy ,"auto" }; ["user" Exposed =Window ,SecureContext ]partial interface FederatedCredential :Credential {readonly attribute USVString ;idToken readonly attribute FederatedCredentialApprovedBy ; };approvedBy
idToken-
The id token.
approvedBy-
When used in conjunction with
mediation, it indicates whether the credential was provided via a § 2.2.1 Auto Sign-in or an § 2.2.2 Explicit Sign-in.
Second, it extends the FederatedCredentialRequestOptions by adding a list of FederatedIdentityProviders:
partial dictionary FederatedCredentialRequestOptions {sequence <(DOMString or FederatedIdentityProvider )>; };providers dictionary {FederatedIdentityProvider required USVString ;url USVString ;clientId USVString ; };nonce
And finally, this specification overrides the FederatedCredential's Method.[[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors)
This algorithm runs in parallel inside the Credential Management § algorithm-request to request credentials and returns a set of FederatedCredential objects from a remote Identity Provider.
This internal method accepts three arguments:
origin-
This argument is the relevant settings object's origin, as determined by the calling
get()implementation, i.e.,CredentialsContainer's Request aCredentialabstract operation. options-
This argument is a
CredentialRequestOptionsobject whoseoptions.member contains afederatedFederatedCredentialRequestOptionsobject specifying the exchange options. sameOriginWithAncestors-
This argument is a Boolean value which is
trueif and only if the caller’s environment settings object is same-origin with its ancestors. It isfalseif caller is cross-origin.
When this method is invoked, the user agent MUST execute the following algorithm:
-
If sameOriginWithAncestors is
false, return a "NotAllowedError"DOMException.Note: This restriction aims to address the concern raised in Security Origin Confusion.
-
Assert: options["
federated"]["providers"] size is 1.Note: At some point we would like to support choosing accounts from multiple Identity Providers.
-
Let wellknown be the result of running the fetch the well-known algorithm with the provider.
-
Let accounts list be the result of running the fetch the accounts list algorithm.
-
Let account be the result of running the select an account from the accounts list algorithm.
-
If the
Account Stateis unregistered-
Return the result of running the sign-up algorithm.
-
-
If the
Session Stateis logged out then-
Return the result of running the explicit sign-in algorithm.
-
-
Return the result of running the auto sign-in algorithm.
To sign-up the user run this algorithm:
-
Gather explicit intent to create an account
-
Gather explicit agreement with the Privacy Policy
-
Gather explicit agreement with the Terms of Service
-
Set the account’s
Account Statefrom unregistered to registered. -
Set the account’s
Session Statefrom logged out to logged in.
To select an account from the accounts list run this algorithm:
-
If accounts list’s size is 1
-
Let account be accounts list[0]
-
Return account
-
-
Display an account chooser
-
Let account be an account that the user manually selects from the accounts chooser
-
Return account
To sign-in the user run this algorithm:
-
Assert that the
Account Stateis registered -
Set the account’s
Session Statefrom logged out to logged in.
To auto sign-in the user run this algorithm:
-
Return the result of running the sign-in algorithm.
To explicit sign-in the user run this algorithm:
-
Gather explicit confirmation that the user wants to sign-in to Relying Party with their Identity Provider's account
-
Return the result of running the sign-in algorithm.
To fetch the well-known configuration file, run this algorithm:
-
Let the wellknown url be the relative url ".well-known/federated-credentials" of provider["
url"] -
Return the result of fetching the wellknown url with the Sec-FedCM-CSRF header but without the Identity Provider's cookies.
To fetch the accounts list run this algorithm:
-
Let the acccounts_endpoint url be the relative url wellknown["
accounts_endpoint"] of provider["url"] -
Let the accounts list be the result of fetching the accounts_endpoint with the Identity Provider's cookies.
-
Return the accounts list
To fetch the client id metadata run this algorithm:
-
Let the client_id_metadata_endpoint url be the relative url wellknown["
client_id_metadata_endpoint"] of provider["url"] -
Let the policies be the result of fetching the client_id_metadata_endpoint with the Sec-FedCM-CSRF header but without the Identity Provider's cookies.
-
Return policies
The Privacy Policy are the policies described at privacy_policy_url.
The Terms of Service are the policies described at terms_of_service_url.
To mint a new id token, run the following algorithm:
-
Let token be the result of making a POST request to the wellknown["
idtoken_endpoint"] with:-
Let the
account_idbe account["account_id"]. -
Let the
requestbe a new object with
-
-
Return a new
FederatedCredentialas:-
idwith account["account_id"] -
idTokenwith token
-
8.2.2. IDP Sign-in API
The IDP Sign-in API allows an IDP to sign the user into a RP by storing a FederatedCredential that can later be retrieved by a RP.
Its effect is equivalent to the § 8.2.1 RP Sign-in API in its effect, except that it is designed to be called while the user is at the IDP rather than at the RP.
async function login({ id, name, iconURL}) { const credential= new FederatedCredential({ id: id, provider: 'https://idp.example' , name: name, iconURL: iconUrl, client_id: "1234" , }); return await navigator. credentials. store( credential); }
8.3. The Revocation API
Whenever the user decides to delete their account on the Relying Party the Relying Party can call an API to let the Identity Provider and the browser know.
Upon return to the Relying Party, the user goes through a § 2.1 Sign-up flow instead of a § 2.2 Sign-in flow.
This specification extends the FederatedCredential interface with an extra static method:
[Exposed =Window ,SecureContext ]partial interface FederatedCredential :Credential {static Promise <void >(revoke USVString ); };accountId
Note: go over the revocation API.
8.4. The Sign-out API
8.4.1. RP Sign-out
When a user wants to log out of their session in the Relying Party, the Relying Party can let the browser know that it wants the § 2.2.1 Auto Sign-in flow to be disabled, so that the user doesn’t get into an infinite loop.
It does so by calling the preventSilentAccess() API, which clear the
user’s current account session and takes them to an § 2.2.2 Explicit Sign-in flow
whenever the user wants to log back in.
Note: go over the RP sign-out API.
8.4.2. IDP Sign-out
In enterprise scenarios, it is common for the user to want to clear all of their existing sessions in all of the Relying Partys they are logged into.
It does so by being navigated to their Identity Provider who initiates what’s called a Front-Channel Logout.
The browser exposes an API that takes the list of Relying Partys that the Identity Provider wants to initiate the logout which are loaded in parallel with cookies.
Each Relying Party endpoint is responsible for clearing its local state (e.g. clearing cookies).
After the completion of this API, the user’s session is cleared and will go through an § 2.2.2 Explicit Sign-in upon return.
async function logout() { await FederatedCredential. logout([{ endpoint: "https://rp1.example" , accountId: "123" , }, { endpoint: "https://rpN.example" , accountId: "456" , }]); }
IDPs can call FederatedCredential.logout(...) to log the user out of the RPs they are signed into.
dictionary {FederatedCredentialLogoutRequest required USVString ;endpoint required USVString ; }; [accountId Exposed =Window ,SecureContext ]partial interface FederatedCredential :Credential {static Promise <void >(logout optional sequence <FederatedCredentialLogoutRequest >= []); };logout_requests
Note: go over how this is implemented.
8.5. Backwards Compatibility
Note: go over how we are planning to deal with backwards compatibility.
9. Security
Note: go over security.
10. Privacy
10.1. Privacy Threat Model
This section is intended to provide a comprehensive overview of the privacy risks associated with federated identity on the web for the purpose of measuring the privacy risks and benefits of proposed browser intermediation designs.
See also:
10.1.1. Principals
This section describes the three principals that would participate in an invocation of the API and expectations around their behavior.
-
The User Agent implements § 8 The Browser API and controls the execution contexts for the RP and IDP content. The user agent is assumed to be trusted by the user, and transitively trusted by the RP and IDP.
-
Relying Partys (RPs) are first party websites that invoke the FedCM API for the purpose of authenticating a user to their account or for requesting information about that user. A well-behaving RP would only invoke the API following a clear user signal -- typically, clicking a sign-in button. Since any site can invoke the API, RPs cannot necessarily be trusted to limit the user information it collects or use that information in an acceptable way.
-
Identity Providers (IDPs) are third party websites that are the target of a FedCM call to attempt to fetch an ID token. Usually the IDP has a higher level of trust than the RP since it already has the user’s personal information, but it is possible that the IDP might use the user’s information in non-approved ways. It is possible that the IDP specified in the API call may not be an IDP the user knows about, or may not be a bona fide IDP at all, in which case it likely does not have personal user information in advance, but also might be less accountable for its behavior.
10.1.2. High-level threats
Privacy Considerations for Internet Protocols describes the following high-level privacy threats, which the TAG has adopted into Self-Review Questionnaire: Security and Privacy § threats:
- Surveillance
-
Surveillance is the observation or monitoring of an individual’s communications or activities.
- Stored Data Compromise
-
End systems that do not take adequate measures to secure stored data from unauthorized or inappropriate access.
- Intrusion
-
Intrusion consists of invasive acts that disturb or interrupt one’s life or activities.
- Misattribution
-
Misattribution occurs when data or communications related to one individual are attributed to another.
- Correlation
-
Correlation is the combination of various pieces of information related to an individual or that obtain that characteristic when combined.
- Identification
-
Identification is the linking of information to a particular individual to infer an individual’s identity or to allow the inference of an individual’s identity.
- Secondary Use
-
Secondary use is the use of collected information about an individual without the individual’s consent for a purpose different from that for which the information was collected.
- Disclosure
-
Disclosure is the revelation of information about an individual that affects the way others judge the individual.
- Exclusion
-
Exclusion is the failure to allow individuals to know about the data that others have about them and to participate in its handling and use.
These threats combine into the particular concrete threats we want web specifications to defend against, described in subsections here:
10.1.3. Attack Scenarios
This section describes the scenarios in which various agents might attempt to gain user information. It considers the possibilities when:
For the purposes of this section, a principal is considered to be participating in the collection of information if it directly or indirectly performs actions with the aim of realizing one of the above threats.
Note: An example of indirect collusion would be an RP importing a script supplied by an IDP where the IDP intends to track users.
For the purpose of discussion this document assumes that third-party cookies are disabled by default and are no longer effective for use in tracking mechanisms, and also some form of mitigations are implemented against ‘bounce tracking’ using link decoration or postMessage. Most of these scenarios consider how user tracking might happen without them.
See also:
10.1.3.1. By the RP
10.1.3.1.1. Cross-Site Correlation
Related to:
Correlation is the combination of various pieces of information related to an individual or that obtain that characteristic when combined.
This attack happens when multiple RPs collude to use their user’s data to correlate them and build a richer profile.
When a user willingly provides their full name, email address, phone number, etc, to multiple relying parties, those relying parties can collaborate to build a profile of that user and their activity across collaborating sites.
Sometimes this is referred to as joining since it amounts to a join of user records between the account databases of multiple RPs.
This correlation and profile-building is outside the user’s control and entirely out of the User Agent’s or IDP’s view.
-
User signs into RP1 (which sells jewelry) with an IDP, providing to RP1 their email address user@email.example
-
User signs into RP2 (which sells houses) with an IDP, providing to RP2 their email address user@email.example
-
User browses the collection of wedding rings in RP1.
-
Out of band, RP1 tells RP2 that user@email.example is shopping for wedding rings
-
User browses the housing inventory in RP2.
-
RP2 uses the fact that the user is shopping for wedding rings in RP1 to advertise and filters their housing inventory.
-
User is surprised that RP2 knows that they are shopping for wedding rings.
A generalization of § 10.1.3.1.1 Cross-Site Correlation is:
(RP Secondary Use) Relying Party uses user information for purposes not authorized by the user:
When the user agrees to allow the IDP to provide information to the RP, the consent is specific to certain purposes, such as sign-in and personalization. The RP might use that data for other purposes that the user would not expect and did not authorize, such as selling email addresses to a spam list.
Spamming risk can exist even when using directed identifiers.
10.1.3.1.2. Same-Site Identification
Identification is the linking of information to a particular individual to infer an individual’s identity or to allow the inference of an individual’s identity.
This attack happens when the Relying Party employs client state-based tracking to identify user.
Any API that exposes any kind of client state to the web risk becoming a vector for fingerprinting or ‘supercookies’.
This risk would be increased by any proposal for browser mediation that adds directly (or indirectly) detectable client state.
For example, an RP can use the browser state of the FedCM to add bits of entropy and fingerprint the user.
See also:
10.1.3.1.3. Data Compromise
This attack scenario happens when the RP takes advantage of inadequate measures (by the IDP or the UA) to secure stored data to obtain personal user information without their consent.
This can happen if user consent mechanisms are missing, inadequate, or susceptible to bypass.
See also:
10.1.3.2. By the IDP
10.1.3.2.1. Secondary Use
Related to:
Secondary use is the use of collected information about an individual without the individual’s consent for a purpose different from that for which the information was collected.
This attack happens when Identity Providers misuses the the information collected to enable sign-in for other purposes.
Existing federation protocols require that the IDP know which service is
requesting an ID token in order to allow identity federation (e.g. the IDP must know the OAuth client_id).
Identity providers can use this fact to build profiles of users across sites where the user has decided to use federation with the same account. This profile could be used, for example, to serve targeted advertisements to those users browsing on sites that the IDP controls.
This risk can exist even in the case where the IDP does not having pre-existing user account information (for instance, if it is not a _bona fide_ IDP), because FedCM requests sent to the IDP are credentialed. This is more likely to occur if the RP is colluding with the IDP to enable tracking; expanded variants are described in § 10.1.3.3.3 Timing Attacks.
-
User signs into RP1 (which sells jewelry) with an IDP.
-
User signs into RP2 (which sells houses) with the same IDP.
-
User navigates to the IDP.
-
Because the IDP knows that the user has an account with RP1 and RP2, the IDP can show ads about vacations for honeymoons.
-
The user is surprised that their IDP is aware of their plans to get married.
10.1.3.2.2. Impersonation
Since IDPs have unconstrained ability to issue ID tokens, they are capable of logging in to users’ federated accounts without user knowledge or action, impersonating the user and potentially gaining full access to the user’s account on the RP.
-
User signs into RP1 (which is a online dating site) with an IDP.
-
An evil employee at IDP is an ex-spouse of the user.
-
The evil employee impersonates themselves as the User and gains access to RP1
-
The evil employee looks at the user’s dating history.
-
The user is surprised by their ex-spouse’s knowledge of their recent dating affairs.
10.1.3.3. By Collusion
10.1.3.3.1. Intrusion
From Target Privacy Threat Model § hl-intrusion
Privacy harms don’t always come from a site learning things.
From RFC6973: Intrusion
Intrusion consists of invasive acts that disturb or interrupt one’s life or activities. Intrusion can thwart individuals' desires to be left alone, sap their time or attention, or interrupt their activities.
In the context of federation, intrusion happens when an RP and an IDP are colluding to invasively and aggressively recommend the user to login disproportionally to the their intent.
Much like unsolicited notifications, an RP can collude with an IDP to aggressively log users in.
See also:
10.1.3.3.2. Back channel
This attack scenario happens when IDP exceed the user’s information sharing permission.
Existing federated identity protocols are clear on what information an RP is requesting, which the IDP can provide. While the browser can inspect the request and response and consider whether user permission has been granted for that transfer, it is difficult to know that there is no additional information embedded in the response. An example could be if the IDP encodes an identifier that could be used to load user-targeted advertisements on RP pages, which could be of value where the IDP has much more profiling information about the user.
Another example is if identifying information is shared out-of-band, invisible to the browser, in which case it could contain anything.
-
User signs into RP1 (which sells jewelry) with an IDP, providing to RP1 their directed identifier email address SHA256(user + RP1)@email.example
-
User signs into RP2 (which sells houses) with an IDP, providing to RP2 their directed identifier email address SHA256(user + RP2)@email.example
-
User browses the collection of wedding rings in RP1.
-
Out of band, RP1 colludes with the IDP and exchanges SHA256(user + RP1)@email.example to user@email.example.
-
RP1 tells RP2 that user@email.example is shopping for wedding rings
-
User browses the housing inventory in RP2.
-
Out of band, RP2 colludes with the IDP and exchanges SHA256(user + RP2)@email.example to user@email.example.
-
RP2 uses the fact that the user is shopping for wedding rings in RP1 to advertise and filters their housing inventory.
-
User is surprised that RP2 knows that they are shopping for wedding rings.
10.1.3.3.3. Timing Attacks
The potential for IDPs profiling users based on their visits to RPs § 10.1.3.2.1 Secondary Use can be partially mitigated by hiding the RP from the IDP until after the user has consented to that tracking risk.
However, there is residual risk in cases where the RP and IDP are colluding.
If a credentialed request is sent to the IDP that does not explicitly identify the RP, either of the following would still allow tracking by the IDP (again, possibly not a _bona fide_ IDP that has existing knowledge of the user):
-
The RP controlling any field in the request that can be used to convey identifying data in the request that the IDP could correlate to other requests from other RPs;
-
The RP being able to provide fine-resolution timing information about the request to the IDP out of band.
The timing information can enable tracking in the following way:
-
The RP logs the time at which it invoked the API, and
-
The IDP logs the time at which it received a credentialed FedCM request from the user, and later
-
They attempt to link the invocation and the request together using that information.
Notably, this is possible without FedCM using simple cross-origin top-level navigations, but using FedCM for this purpose would worsen the problem if it improved timing resolution or was less visible to users.
See also:
10.2. Mitigation Strategies
In this section we’ll go over some strategies used in this specification to mitigate the privacy threats.
10.2.1. Minimal Disclosure
There is a series of privacy threats that can be mitigated by disclosing the least amount of identifying information and limiting its use as much as possible. Two notable strategies are described in the sections below.
10.2.1.1. Directed Identifiers
Mitigates:
Note: directed, sharding, partitioning
The problem of RPs joining user data via back-channels is inherent to the proliferation of identifying user data. This can be solved by issuing directed identifiers that provide an effective handle to a user’s identity with a given IDP that is unique and therefore cannot be correlated with other RPs.
In the past, there have been schemes to accomplish this using one-way hashes of, for example, the user’s name, the IDP and the RP.
Note: this mitigation is not robust against § 10.1.3.3.2 Back channel, or the § 10.1.3.2.1 Secondary Use. Also, collaborating RPs might be able to defeat this mitigation by sharing the same CLIENT_ID, although possibly this could be detected and presumably would violate RP agreements with IDPs with § 10.2.5 Pre-registration.
10.2.1.2. Self Presentation
Mitigates:
Note: unbundling issuing from presentation
Preventing tracking of users by the IDP is difficult because the RP has to be coded into the identity token for security reasons, to prevent reuse of the token. There have been cryptographic schemes developed to blind the IDP to the RP while still preventing token reuse in that way (see Mozilla’s personas) but there are other valid uses that the IDP has for knowing the RP, such as fraud and abuse prevention.
10.2.2. Mediation
Mitigates:
IDPs, whom the user has entrusted with their personal data, are currently responsible for ensuring that the user consents to their information being shared. With browser mediation in place, the user agent might have to assume responsibility for ensuring the user understands what is being shared and that it is intentional. This is certainly the case if the browser is able to entirely intermediate the identity flow without showing any IDP web content, but also might be desirable if there are concerns that the IDP is not collecting consent in an adequate manner.
Additionally, a consent prompt preceding the sharing of the RP’s request to the IDP can mitigate risks around IDP tracking of user visits to RPs.
See also:
-
Self-Review Questionnaire: Security and Privacy § user-mediation
-
Ethical Principles: The web must make it possible for people to verify the information they see
-
Ethical Principles: The web must enhance individuals' control and power
10.2.2.1. Verification
Mitigates:
The User Agent can mitigate § 10.1.3.1.1 Cross-Site Correlation by inspecting the contents of the data exchange, and providing the necessary user controls.
For example, it can inspect the email address that is being exchanged and verify whether it is a directed identifier or not (and warn the user proportionally).
10.2.2.2. Activation
The User Agent can mitigate § 10.1.3.3.1 Intrusion by mediating the user controls and offering them proportionally to the intent of the user or the privacy risks involved.
For example, a User Agent can choose to show a loud / disruptive modal mediated dialog when it has enough confidence of the user’s intent or show a quiet / conservative UI hint when it doesn’t.
A User Agent could also choose to control disruption of the user’s experience based on the risks involved.
For example, when a directed identifier is being exchanged it can be more confident of the unintended consequeces and offer a more aggressive user experience, whereas when global identifiers are exchanged a more conservative user experience.
See also:
10.2.3. Policy
Mitigates:
Beyond technical constraints, the browser can recognize explicit assertions by the IDP about the privacy characteristics it provides and rely on those assertions in order to guide the user appropriately. An example is a hypothetical case in which the IDP asserts it will only issue directed identifiers and will not provide identifying information to the RPs out of view of the browser. In that case the browser may not have to warn the user about sharing personalized information.
10.2.4. Denylists
Mitigates:
-
Potentially all threats, but is subject to the likelihood of bad behavior being detected, which for some might be difficult.
Any RPs or IDPs observed to be using this API to compromise user privacy in a deceptive or abusive manner could be explicitly blocked from using it, or potentially added to the SafeBrowsing blocklist so that they cannot be loaded at all.
10.2.5. Pre-registration
Mitigates:
Currently, IDPs require that an RP pre-registers and agrees to specific terms before the IDP will issue an ID token to them. This conflicts with the previous mitigation, but can provide a measure of RP accountability.
10.2.6. 2FA
Mitigates:
11. Extensibility
Note: go over the extensibility mechanisms.
12. Acknowledgements
Note: write down the Acknowledgements section.